Read More block: add aria-label and screen reader text #45490

jffng · 2022-11-02T14:56:37Z

What?

This PR adds ~~an aria-label and~~ .screen-reader-text to the output of the Read More block. I could use some input as to whether the resulting markup is acceptable.

Why?

Fixes 1/2 of #45396

Links must avoid repetitive non-contextual text strings such as ‘read more…’ and must make sense if taken out of context. Bare urls must not be used as links. Supporting text may use a screen reader class to hide text visually.

https://make.wordpress.org/themes/handbook/review/accessibility/required/#repetitive-link-text

How?

See above.

Testing Instructions

Check out this PR and add the following block markup for a Query to a post or template:

<!-- wp:query {"queryId":0,"query":{"perPage":3,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":false}} -->
<div class="wp-block-query"><!-- wp:post-template -->
<!-- wp:post-title /-->
<!-- wp:post-featured-image /-->
<!-- wp:read-more /-->
<!-- /wp:post-template -->
<!-- wp:query-pagination -->
<!-- wp:query-pagination-previous /-->
<!-- wp:query-pagination-numbers /-->
<!-- wp:query-pagination-next /-->
<!-- /wp:query-pagination --></div>
<!-- /wp:query -->

Ensure the resulting markup for the Read More link is accessible. Here is an example:

<a class="wp-block-read-more" href="http://gutenbergtest.local/341-2/" target="_self" aria-label="Post ID: 341">Continue Reading<span class="screen-reader-text">This is my post title</span></a>

Screenshots or screencast

codesandbox · 2022-11-02T14:56:40Z

Open in CodeSandbox Web Editor | VS Code | VS Code Insiders

carolinan · 2022-11-02T18:57:12Z

Thank you for working on this Jeff.
When an aria-label is added to a link, the aria-label replaces any link text.
When I test the PR with VoiceOver, it reads: "Visited, link, Post ID: 158" even if a valid link text is added.
Edit: It also meant that the screen reader text didn't show up in the top corner of the screen.

Did you intend to use the Post ID only if there is no post title?

jffng · 2022-11-02T19:10:11Z

Ah I see, thank you for explaining, I'm quite new to working on accessibility issues.

Did you intend to use the Post ID only if there is no post title?

I used the post ID here because of the comment in the original issue:

The block should always include relevant details to clarify the link target using one of aria-label, aria-describedby with a reference pointing to the title by ID

Maybe I misunderstood the feedback, and it would make sense to return a better description (e.g. Read more about "My Post Title"), and use only the post ID if there is no post title. How does that sound?

carolinan · 2022-11-02T19:27:38Z

It would solve part of the issue if the default visible text was changed from "Read more" to "Read more about post title".

The problem with that is that it would change the text for users who are using the old default and it may be unexpected for them.

Just brainstorming:

Make the updated text the new default visible text
Add a setting to visually hide the post title
Enable that setting for existing blocks, so that users who are using the current default, see no change (I don't know how to do this :) )
For scenarios where the text has been edited, add an aria-describedby with the post title.

If we are choosing between aria-label and screen reader text, I think that screen reader text may help more people since it is also visible, even if only when the link is focused?

jffng · 2022-11-03T16:12:02Z

If we are choosing between aria-label and screen reader text, I think that screen reader text may help more people since it is also visible, even if only when the link is focused?

👍 I will update the PR accordingly.

joedolson · 2022-11-03T19:03:32Z

The reference "pointing to the title by ID" refers to the mechanism of using aria-describedby. Simple example code would be like so:

<h2 id="post-58">Title</h2><a href="permalink" aria-describedby="post-58">Read more</a>

That creates a relationship between 'read more' and the post title so that the link is described by the title, and the reference is to the ID attribute of the post title.

Using screen reader text is, however, probably a better solution, as it is supported in a broader capacity and easier to make visible when needed.

jffng · 2022-11-03T19:17:38Z

Thanks for the clarification. Would the redundancy of having both aria-describedby and screen reader text be helpful, or is it sufficient to only provide the screen reader text with a sensible message e.g. Read more about "My Post Title"?

joedolson · 2022-11-03T19:23:22Z

No, only provide one option. Having both, e.g.

<h2 id="post-58">Post Title</h2><a href="permalink" aria-describedby="post-58">Read more<span class="screen-reader-text"> about "Post Title"</span></a>

would result in reading "Read more about Post Title [pause] Post Title"; the redundancy would mostly just be annoyingly verbose.

carolinan · 2022-11-04T04:49:55Z

VoiceOver reads this change as:

Without custom text, with post title: "visited link, Read more read more about post title"
With custom text, with post title "visited link, custom text read more about post title"
Without post title: "visited link, Read more read more about"

(I do not hear a pause, but I am not a screen-reader user)
Nit:
Please use sprintf and a translators comment for the combination of the screen reader text and title

jffng · 2022-11-04T17:39:47Z

Thanks for the feedback and bearing with me!

I pushed a commit that attempts to make the screen reader text more compatible with all scenarios, using a colon instead of "Read more about" to avoid the redundancy — what do you think?

joedolson

It's looking good! Some changes still need consideration.

joedolson · 2022-11-06T20:20:47Z

packages/block-library/src/read-more/index.php

 	$justify_class_name = empty( $attributes['justifyContent'] ) ? '' : "is-justified-{$attributes['justifyContent']}";
 	$wrapper_attributes = get_block_wrapper_attributes( array( 'class' => $justify_class_name ) );
 	$more_text          = ! empty( $attributes['content'] ) ? wp_kses_post( $attributes['content'] ) : __( 'Read more' );
 	return sprintf(
-		'<a %1s href="%2s" target="%3s">%4s</a>',
+		'<a %1s href="%2s" target="%3s">%4s<span class="screen-reader-text">%5s</span></a>',


There needs to be a space between the visible link text and the hidden text, otherwise the words will be pasted together. e.g. <a %1s href="%2s" target="%3s">%4s<span class="screen-reader-text"> %5s</span></a>

See the space inside the screen-reader-text span.

To make "grammatical" sense in cases where the user has customized the "read more" text, I went with the following format:

Read More: Post Title

See https://github.com/WordPress/gutenberg/pull/45490/files#diff-5fed9d866f33e17d5bf917f312bcae02af3c8bd244586ab161ed60889c960af6R25

Does that make sense?

Great. Also good for internationalization.

joedolson · 2022-11-06T20:21:48Z

packages/block-library/src/read-more/index.php

+	/* translators: %s is either the post title or post ID to describe the link for screen readers. */
+	$screen_reader_text = sprintf(
+		__( ': %s' ),
+		$post_title !== '' ? $post_title : __( 'post ' ) . $post_ID


What's the use case where the post has no title? The post ID does differentiate links, but not in any way that's useful to the user, so I'm wondering if there's a better fallback option.

Hmm I'm not sure. We could use aria-describedby in this case, but again not sure if this is any more useful because it's linking the read more to a post that has no title.

Would it be better to state that there is no post title, e.g. Read More: (post with no title)?

In the scenario where an implementation uses primarily posts with no titles (ugly, but I've seen it), that would result in a series of identical links. Perhaps a combination, e.g. Read More: untitled post $post_ID

Perhaps a combination, e.g. Read More: untitled post $post_ID

Done in 369691d

jffng · 2022-11-09T22:31:14Z

@alexstine would you be able to give this a review?

tellthemachines

Code looks good and it's working well in testing on VoiceOver/Safari. When post has a title, it's reading "Read more: post title". If there's no title, it reads "Read more: untitled post 234".

alexstine · 2022-11-10T00:56:12Z

@tellthemachines Thanks for testing/reviewing, I have been swamped with day job stuff lately.

@jffng Awesome improvement, thanks.

youknowriad · 2023-02-07T07:36:52Z

packages/block-library/src/read-more/index.php

+	$screen_reader_text = sprintf(
+		/* translators: %s is either the post title or post ID to describe the link for screen readers. */
+		__( ': %s' ),
+		'' !== $post_title ? $post_title : __( 'untitled post ' ) . $post_ID


We received this feedback related to this change https://core.trac.wordpress.org/ticket/57471#comment:27

Basically we should avoid concatenation when it comes to translated strings.

Let's make sure to follow-up on that and label the PR with the "backport to WP beta/RC" label to include on the next package update in core.

Tracked here #47812

jffng added [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). [Block] Read More Affects the Read More Block labels Nov 2, 2022

jffng requested a review from ajitbohra as a code owner November 2, 2022 14:56

jffng requested a review from joedolson November 2, 2022 14:56

jffng force-pushed the add/read-more-accessible-output branch from 409da8d to 12c24f7 Compare November 3, 2022 16:24

jffng requested a review from carolinan November 3, 2022 18:48

joedolson requested changes Nov 6, 2022

View reviewed changes

jffng added 4 commits November 8, 2022 12:27

Add aria label + screen reader text to the link.

b89f5c6

Use only screen reader text.

83e2d93

Make the screen reader text more universal.

7b55ab1

Make the screen reader text explicit when the post is untitled.

d98f6ad

jffng force-pushed the add/read-more-accessible-output branch from 369691d to d98f6ad Compare November 8, 2022 19:28

jffng added 2 commits November 9, 2022 10:24

Make linter happy.

676e477

Move translators note and fix Yoda.

7928e6f

tellthemachines approved these changes Nov 10, 2022

View reviewed changes

jffng merged commit 780def8 into trunk Nov 10, 2022

jffng deleted the add/read-more-accessible-output branch November 10, 2022 00:55

github-actions bot added this to the Gutenberg 14.6 milestone Nov 10, 2022

jffng mentioned this pull request Nov 10, 2022

Post Excerpt block: add aria-label and screen reader text #45491

Open

carolinan mentioned this pull request Dec 29, 2022

Improve prompt to edit "read more" text #46639

Open

youknowriad reviewed Feb 7, 2023

View reviewed changes

youknowriad mentioned this pull request Feb 7, 2023

Wrong string concatenation for the read more block. #47812

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Read More block: add aria-label and screen reader text #45490

Read More block: add aria-label and screen reader text #45490

jffng commented Nov 2, 2022 •

edited

Loading

codesandbox bot commented Nov 2, 2022

carolinan commented Nov 2, 2022 •

edited

Loading

jffng commented Nov 2, 2022

carolinan commented Nov 2, 2022

jffng commented Nov 3, 2022 •

edited

Loading

joedolson commented Nov 3, 2022

jffng commented Nov 3, 2022

joedolson commented Nov 3, 2022

carolinan commented Nov 4, 2022 •

edited

Loading

jffng commented Nov 4, 2022

joedolson left a comment

joedolson Nov 6, 2022

jffng Nov 7, 2022

joedolson Nov 7, 2022

joedolson Nov 6, 2022

jffng Nov 7, 2022 •

edited

Loading

joedolson Nov 7, 2022

jffng Nov 7, 2022

jffng commented Nov 9, 2022

tellthemachines left a comment

alexstine commented Nov 10, 2022

youknowriad Feb 7, 2023 •

edited

Loading

youknowriad Feb 7, 2023

Read More block: add aria-label and screen reader text #45490

Read More block: add aria-label and screen reader text #45490

Conversation

jffng commented Nov 2, 2022 • edited Loading

What?

Why?

How?

Testing Instructions

Screenshots or screencast

codesandbox bot commented Nov 2, 2022

carolinan commented Nov 2, 2022 • edited Loading

jffng commented Nov 2, 2022

carolinan commented Nov 2, 2022

jffng commented Nov 3, 2022 • edited Loading

joedolson commented Nov 3, 2022

jffng commented Nov 3, 2022

joedolson commented Nov 3, 2022

carolinan commented Nov 4, 2022 • edited Loading

jffng commented Nov 4, 2022

joedolson left a comment

Choose a reason for hiding this comment

joedolson Nov 6, 2022

Choose a reason for hiding this comment

jffng Nov 7, 2022

Choose a reason for hiding this comment

joedolson Nov 7, 2022

Choose a reason for hiding this comment

joedolson Nov 6, 2022

Choose a reason for hiding this comment

jffng Nov 7, 2022 • edited Loading

Choose a reason for hiding this comment

joedolson Nov 7, 2022

Choose a reason for hiding this comment

jffng Nov 7, 2022

Choose a reason for hiding this comment

jffng commented Nov 9, 2022

tellthemachines left a comment

Choose a reason for hiding this comment

alexstine commented Nov 10, 2022

youknowriad Feb 7, 2023 • edited Loading

Choose a reason for hiding this comment

youknowriad Feb 7, 2023

Choose a reason for hiding this comment

jffng commented Nov 2, 2022 •

edited

Loading

carolinan commented Nov 2, 2022 •

edited

Loading

jffng commented Nov 3, 2022 •

edited

Loading

carolinan commented Nov 4, 2022 •

edited

Loading

jffng Nov 7, 2022 •

edited

Loading

youknowriad Feb 7, 2023 •

edited

Loading